View CP2101_8929596.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

rev. 2.3 11/13 copyright ? 2013 by silicon laboratories an169 an169 usbx press ? p rogrammer ? s g uide 1. introduction the silicon laboratories usbxpress ? development kit provides a complete host and device software solution for interfacing silicon laboratories c8051f32x, c80 51f34x, c8051f38x, c8051t32x, and c8051t62x usb mcus and cp210x communication bridges to the universal serial bus (usb). no usb protocol or host device driver expertise is required. instead, a simple, high-level applic ation program interface (api) for both the host software and device firmware is used to provide complete usb connectivity. the usbxpress development kit includes windows device driv ers, windows device driver installer, host interface function library (host api) provided in the form of a windows dynamic link library (dll), and device firmware interface function library (c8051f32x, c8051f34x, c 8051f38x, c8051t32x, and c8051t62x devices only). figure 1. usbxpress data flow relevant devices this application note applies to the following devices: c8051f32x, c8051f34x, c8051f38x, c8051t32x, c8051 t62x, CP2101, cp2102, cp2103, cp2104, cp2105, cp2108, cp2109 user application (eg. vc++ custom app) usbxpress dll / api usbxpress driver pc usb root hub usb usbxpress firmware library user firmware 'f32x/'f34x/'f38x/'t32x/'t62x cp210x usb-uart bridge external rs-232 transceiver or uart circuitry user application (eg. vc++ custom app) usbxpress dll / api usbxpress driver pc usb root hub usb
an169 2 rev. 2.3 2. usbxpress versions the usbxpress v4.0 and above driver inco rporates microsoft's winu sb driver rather than the proprietary driver of v3.x, and both the underlying driver and the dll have cha nged. to use usbxpress v4.0 , install the latest driver from the website ( www.silabs.com/interface-software ) and upgrade the dll. the api to the dll remains unchanged, but there is one new api call added to the library: si_cancelio() . this api call replaces cancelio() and should be used if the software calls si_read() or si_write() in overlapped mode and the software needs to cancel i/o operations. the si_cancelio() function cancels read and write requests in both the dll buffer and the driver buffer, whereas cancelio() only cancels requests in the driver buffer, leaving outstanding requests in the dll. the an220 driver customization software provides an option to customize either the v4.0 and above driver or the v3.x driver for legacy ap plications. customizations of the v4.0 and above winusb driver will still require recertification through microsoft. the an220 software can be found here: www.silabs.com/interface-appnotes .
an169 rev. 2.3 3 3. host api functions the host api is provided in the form of a windows dynamic link library (dll). the host interface dll communicates with the usb device via the provided de vice driver and the operating system's usb stack. the following is a list of the host api functions available: si_getnumdevices() - returns the number of devices connected si_getproductstring() - returns a descriptor for a device si_open() - opens a device and returns a handle si_close() - cancels pending io and closes a device si_read() - reads a block of data from a device si_write() - writes a block of data to a device si_cancelio() - cancels outstanding overlapped io si_flushbuffers() - flushes the tx and rx buffers for a device si_settimeouts() - sets read and write block timeouts si_gettimeouts () - gets read and write block timeouts si_checkrxqueue() - returns the number of byte s in a device's rx queue si_setbaudrate() - sets the specified cp210x baud rate si_setbauddivisor() - sets the specified cp210x baud divisor value si_setlinecontrol() - sets the cp210x device line control si_setflowcontrol() - sets the cp210x device flow control si_getmodemstatus() - gets the cp210x device modem status si_setbreak() - sets the break state for cp210x device. si_readlatch() - gets the port latch value from a cp2103 device si_writelatch() - sets the port latch value to a cp2103 device si_getpartnumber() - gets the cp210x device part number si_deviceiocontrol() - allows sending low-level co mmands to the device driver si_getdllversion() - gets the version of the dll currently in use si_getdriverversion() - gets the version of the usbxpress driver in general, the user initiates communication with the target usb device(s) by making a call to si_getnumdevices . this call will return the number of target devices. this number is then used as a range when calling si_getproductstring to build a list of device serial numbers or product description strings. to access a device, it must first be opened by a call to si_open using an index determined from the call to si_getnumdevices . the si_open function will return a handle to the de vice that is used in all subsequent accesses. data i/o is performed using the si_write and si_read functions. when i/o operations are complete, the device is closed by a call to si_close . additional functions are provided to flush the transmit and receive buffers ( si_flushbuffers ), set receive and transmit timeouts ( si_settimeouts ), check the receive buffer's status ( si_checkrxqueue ), and miscellaneous device control ( si_deviceiocontrol ). for cp210x devices, functions are available to set the baud rate ( si_setbaudrate ); set the baud divisor ( si_setbauddivisior ); adjust the line control settings such as word length, stop bits, and parity ( si_setlinecontrol ); set hardware handshaking, software handshaking, and modem control signals ( si_setflowcontrol ); and get modem status ( si_getmodemstatus ). additional functions are available for cp2103/4/5/8 devices to get ( si_readlatch ) and set ( si_writelatch ) the values of the additional gpio pins availabl e on the device. in order to differentiate between cp210x devices, a function ( si_getpartnumber ) has been provided to return the part number. each of these functions are described in detail in the follo wing sections. type definitions and constants are defined in "appendix d?definitions from c++ header file siusbxp.h?.
an169 4 rev. 2.3 3.1. si_getnumdevices description: this function returns the number of devices connected to the host. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9/ prototype: si_status si_getnumdevices (lpdword numdevices) parameters: 1. numdevices ?address of a dword va riable that will contain the number of devices connected on return. return value: si_status = si_success or si_device_not_found or si_invalid_parameter 3.2. si_getproductstring description: this function returns a null terminated serial number (s/n) string or product description string for the device specified by an index passed in device num. the index for the first device is 0 and the last device is the value returned by si_getnumdevices ? 1. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_getproductstring (dword devicenum, lpvoid devicestring, dword options) parameters: 1. devicenum ?index of the device for which the produ ct description string or serial number string is desired. 2. devicestring ?variable of type si_device_string which will contain a null terminated device descriptor or serial number string on return. 3. options ?dword containing flags to determine if devicestring contains a serial number, product description, vendor id, or product id string. see "appendix d?definitions from c++ header file siusbxp.h? for flags. return value: si_status = si_success or si_device_not_found or si_invalid_parameter
an169 rev. 2.3 5 3.3. si_open description: opens a device (using device number as returned by si_getnumdevices ) and returns a handle which will be used for s ubsequent accesses. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_open (dword devicenum, handle *handle) parameters: 1. devicenum ?device index. 0 for first device, 1 for 2nd, etc. 2. handle ?pointer to a variable where the handle to th e device will be stored. this handle will be used by all subsequent ac cesses to the device. return value: si_status = si_success or si_device_not_found or si_invalid_parameter or si_global_data_error 3.4. si_close description: closes an open device using the handle provided by si_open and sets the handle to invalid_handle_value. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_close (handle handle) parameters: 1. handle ?handle to the device to close as returned by si_open . return value: si_status = si_success or si_invalid_handle or si_system_error_code or si_global_data_error
an169 6 rev. 2.3 3.5. si_read description: reads the available number of bytes into the supplied buffer and retrieves the number of bytes that were read (this can be less than the number of bytes requested). th is function returns syn- chronously if the overla pped object is set to null (this hap pens by default) but will not block sys- tem execution. if an initializ ed overlapped object is passed then the function returns immediately. if the read completed then the stat us will be si_success but if i/o is still pending then it will return status_io_pending. if st atus_io_pending is returned, the over- lapped object can then be waited on using waitfors ingleobject(), and re trieve data or cancel using getoverlappedresult() (as documented on msdn by microsoft) or si_cancelio() respec- tively. this functionality allows for multiple reads to be issued and waited on at a time. if any data is available when si_read is called it will return so check nu mbytesreturned to determine if all requested data was returned. to make sure that si_read returns the requested number of bytes use si_checkrxqueue() described in section "3.11. si_checkrxqueue" on page 9. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_read (handle handle, lpvoid buffer, dword numbytestoread, dword *numbytesreturned, overlapped* o = null) parameters: 1. handle ?handle to the device to read as returned by si_open . 2. buffer ?address of a character buffer to be filled with read data. 3. numbytestoread ?number of bytes to read from the device into the buffer (0?64 kb). 4. numbytesreturned ?address of a dword which will contain the number of bytes actually read into the buffer on return. 5. (optional) ?address of an initialize d overlapped object that can be used for asynchronous reads. return value: si_status = si_success or si_read_error or si_invalid_parameter or si_invalid_handle or si_si_read_timed_out or si_io_pending or si_system_error_code or si_invalid_request_length or si_device_io_failed
an169 rev. 2.3 7 3.6. si_write description: writes the specified number of bytes from the su pplied buffer to the device. this function returns synchronously if the overlapped object is set to null (thi s happens by default) but will not block system execution. an initialized overlapped object may be specified and waited on just as described in the description for si_read() , section "3.5. si_read" on page 6. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_write (handle handle, lpvoid buffer, dword numbytestowrite, dword *numbyteswritten, overlapped* o = null) parameters: 1. handle ?handle to the device to write as returned by si_open . 2. buffer ?address of a character buffer of data to be sent to the device. 3. numbytestowrite ?number of bytes to write to the device (0?4096 bytes). 4. numbyteswritten ?address of a dword which will co ntain the number of bytes actually written to the device. 5. (optional) ?address of an initialize d overlapped object that can be used for asynchronous writes. return value: si_status = si_success or si_write_error or si_invalid_reque st_length or si_invalid_parameter or si_invalid_handle or si_write_timed_out or si_io_pending or si_system_error_code or si_device_io_failed 3.7. si_cancelio description: cancels any pending io on a devic e opened with an overlapped object. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_cancelio (handle handle) parameters: 1. handle ?handle to the device to write as returned by si_open . return value: si_status = si_success or si_invalid_handle or si_system_error_code or si_global_data_error
an169 8 rev. 2.3 3.8. si_flushbuffers description: on usb mcu devices, this function flushes both the receive buffer in the usbxpress device driver and the transmit buffer in the device. note: parameter 2 and 3 have no effect and any value can be passed when used with usb mcu devices. on cp210x devices, this function operates in acco rdance with parameters 2 and 3. if parameter 2 (flushtransmit) is non-zero, the cp210x device?s uart transmit buffer is flushed. if parameter 3 (flushreceive) is non-zero, the cp210x device?s uart receive buffer is flushed. if parameters 2 and 3 are both non-zero, then both the cp210x device uart transmit buffer and uart receive buffer are flushed. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_flushbuffers (handle handle, byte flushtransmit, byte flushreceive) parameters: 1. handle ?handle to the device as returned by si_open . 2. flushtransmit ?set to a non-zero value to flush the cp210x uart transmit buffer. 3. flushreceive ?set to a non-zero value to flush the receive buffer. return value: si_status = si_success or si_invalid_handle or si_system_error_code 3.9. si_settimeouts description: sets the read and write timeouts. timeouts are used for si_read and si_write when called syn- chronously (overlapped* o is set to null). the default value for timeouts is infinite (0xffffffff), but they can be set to wait for any number of milliseconds between 0x0 and 0xfffffffe. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_settimeouts (dword readtimeout, dword writetimeout) parameters: 1. readtimeout ? si_read operation timeout (in milliseconds). 2. writetimeout ? si_write operation timeout (in milliseconds). return value: si_status = si_success or si_device_io_failed
an169 rev. 2.3 9 3.10. si_gettimeouts description: returns the current read and write timeouts. if a timeout value is 0xffffffff (infinite) it has been set to wait infinitely ; otherwise the timeouts ar e specified in milliseconds. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_gettimeouts (lpdword readtimeout, lpdword writetimeout) parameters: 1. readtimeout ? si_read operation timeout (in milliseconds). 2. writetimeout ? si_write operation timeout (in milliseconds). return value: si_status = si_success or si_invalid_parameter or si_device_io_failed 3.11. si_checkrxqueue description: returns the number of bytes in the receive queue and a status value that indicates if an overrun (si_queue_overrun) has occurred and if th e rx queue is ready (si_queue_ready) for reading. upon indication of an overrun condit ion it is recommended that data transfer be stopped and all buffers be flushed using the si_flushbuffers command. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_checkrxqueue (handle handle, lpdword numbytesinqueue, lpdword queuestatus) parameters: 1. handle ?handle to the device as returned by si_open . 2. numbytesinqueue ?address of a dword variable that contains the number of bytes currently in the receive queue on return. 3. queuestatus ?address of a dword variable that contains the si_rx_empty (also si_rx_no_overrun), si_rx_ove rrun, or si_rx_ready flag. return value: si_status = si_success or si_device_io_failed or si_invalid_handle or si_invalid_parameter
an169 10 rev. 2.3 3.12. si_setbaudrate description: sets the baud rate. refer to the device data sheet for a list of baud rates supported by the device. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_setbaudrate (handle handle, dword dwbaudrate) parameters: 1. handle ?handle to the device as returned by si_open . 2. dwbaudrate ?a dword value specifying the baud rate to set. return value: si_status = si_success or si_invalid_baudrate or si_invalid_handle or si_invalid_parameter or si_device_io_failed 3.13. si_setbauddivisor description: sets the baud rate directly by using a specific divisor value. this function is obsolete; use si_setbaudrate instead. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_setbauddivisor (handle handle, word wbauddivisor) parameters: 1. handle ?handle to the device as returned by si_open . 2. wbauddivisor ?a word value specifying the baud divisor to set. return value: si_status = si_success or si_invalid_handle or si_invalid_parameter or si_device_io_failed
an169 rev. 2.3 11 3.14. si_setlinecontrol description: adjusts the line control settings: word length, stop bits, and parity. refer to the device data sheet for valid line co ntrol settings. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_setlinecontrol (handle handle, word wlinecontrol) parameters: 1. handle ?handle to the device as returned by si_open . 2. wlinecontrol ?a word variable that contains the desired line control settings. possible input settings are as follows: bits 0?3 number of stop bits 0: 1 stop bit; 1: 1.5 stop bits; 2: 2 stop bits bits 4?7 parity 0: none 1: odd 2: even 3: mark 4: space bits 8?15 number of bits per word 5, 6, 7, or 8 return value: si_status = si_success or si_device_io_failed or si_invalid_handle or si_invalid_parameter
an169 12 rev. 2.3 3.15. si_setflowcontrol description: adjusts the following flow control settings: se t hardware handshaking, software handshaking, and modem control signals. see "appendix d?definitions from c++ header file siusbxp.h? for pin characteristic definitions. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_setflowcontrol (handle handle, byte bcts_maskcode, byte brts_maskcode, byte bdtr_maskcode, byte bdsrmaskcode, byte bdcd_maskcode, byte bflowxonxoff) parameters: 1. handle ?handle to the device as returned by si_open . 2. bcts_maskcode ?the cts pin characteristic must be as follows: si_status_input or si_handshake_line. 3. brts_maskcode ?the rts pin characteristic must be as follows: si_held_active, si_held_inactive, si_firmware_controlled or si_transmit_active_signal. 4. bdtr_maskcode ?the dtr pin characteristic must be as follows: si_held_inactive, si_held_active or si_firmware_controlled. 5. bdsr_maskcode ?the dsr pin characteristic must be as follows: si_status_input or si_handshake_line. 6. bdcd_maskcode ?the dcd pin characteristic must be as follows: si_status_input or si_handshake_line. 7. bflowxonxoff ?sets software flow control to be off if the value is 0, and on using the character value specified if value is non-zero. return value: si_status = si_success or si_device_io_failed or si_invalid_handle or si_invalid_parameter
an169 rev. 2.3 13 3.16. si_getmodem status description: gets the modem status from the device . this includes the modem pin states. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_getmodemstatus (handle handle, pbyte modemstatus) parameters: 1. handle ?handle to the device as returned by si_open . 2. lpbmodemstatus ?address of a byte variable that contains the current states of the rs-232 modem control lines. the byte is defined as follows: bit 0: dtr state bit 1: rts state bit 4: cts state bit 5: dsr state bit 6: ri state bit 7: dcd state return value: si_status = si_success or si_device_io_failed or si_invalid_handle or si_invalid_parameter 3.17. si_setbreak description: sends a break state (transmit or reset) to a cp2 10x device. note that this function is not neces- sarily synchronized with queued transmit data. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_setbreak(handle cyhandle, word wbreakstate) parameters: 1. handle ?handle to the device as returned by si_open. 2. wbreakstate ?the break state to set. if this value is a 0x0000 then the break is reset. if this value is a 0x0001 then a break is transmitted. return value: si_status = si_success or si_device_io_failed or si_invalid_handle or si_invalid_parameter
an169 14 rev. 2.3 3.18. si_readlatch description: gets the current port latch value (least significant four bits) from the device. supported devices: cp2103/4/5 prototype: si_status si_readlatch (handle handle, lpbyte latch) parameters: 1. handle ?handle to the device as returned by si_open . 2. latch ?pointer for a return port latch value (logic high = 1, logic low = 0). return value: si_status = si_success or si_device_not_found or si_function _not _supported or si_global_data_error or si_invalid_handle or si_invalid_parameter or si_device_io_failed 3.19. si_writelatch description: sets the current port latc h value (least significant four bits) from the device. supported devices: cp2103/4/5 prototype: si_status si_writelatch (handle handle, byte mask, byte latch) parameters: 1. handle ?handle to the device as returned by si_open . 2. mask ?determines which pins to change (change = 1, leave = 0). 3. latch ?value to write to the port latch (logic high = 1, logic low = 0). return value: si_status = si_success or si_device_not_found or si_function _not _supported or si_global_data_error or si_invalid_handle or si_invalid_parameter or si_device_io_failed 3.20. si_getpartnumber description: retrieves the part number of the cp210x device for a given handle. supported devices: CP2101/2/3/4/5/8/9 prototype: si_status si_getpartnumber (handle handle, lpbyte partnum) parameters: 1. handle ?handle to the device as returned by si_open . 2. latch ?pointer for a return part number. return value: si_status = si_success or si_invalid_parameter or si_invalid_handle or si_device_io_failed
an169 rev. 2.3 15 3.21. si_deviceiocontrol description: interface for any miscellane ous device control functions. a separate call to si_deviceiocontrol is required for each input or output operation. a single call cannot be used to perform both an input and output operation simultaneously. refer to deviceiocontrol function definition on msdn help for more details. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: si_status si_deviceiocontrol (handle handle, dword iocontrolcode, lpvoid inbuffer, dword bytestoread, lpvoid outbuffer, dword bytestowrite, lpdword bytessucceeded) parameters: 1. handle ?handle to the device as returned by si_open . 2. iocontrolcode ?code to select control function. 3. inbuffer ?pointer to input data buffer. 4. bytestoread ?number of bytes to be read into inbuffer. 5. outbuffer ?pointer to output data buffer. 6. bytestowrite ?number of bytes to write from outbuffer. 7. bytessucceeded ?address of a dword variable that will contain the number of bytes read by a input operation or the number of bytes written by a output operation on return. return value: si_status = si_success or si_device_io_failed or si_invalid_handle 3.22. si_getdllversion description: obtains the version of the dll that is currently in use. the version is returned in two dword values, highversion and lowversion. this corres ponds to version a.b.c.d where a = (highver- sion >> 16) & 0xffff, b = highversion & 0xffff, c = (lowversion >> 16) & 0xffff and d = lowversion & 0xffff. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_getdllversion (dword* highversion,dword* lowversion) parameters: 1. highversion?address of a dword variable that will contain the top 32 bits of the dll version. 2. lowversion?address of a dword variable that wi ll contain the bottom 32 bits of the dll version. return value: si_status = si_success or si_system_error_code
an169 16 rev. 2.3 3.23. si_getdriverversion description: obtains the version of the driver that is currently in the windows system directory. the version is returned in two dword values, highversion and lowversion. this corresponds to version a.b.c.d where a = (highversion >> 16) & 0xfff f, b = highversion & 0xffff, c = (lowversion >> 16) & 0xffff and d = lowversion & 0xffff. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 prototype: si_status si_getdriverversion (dword* highversion,dword* lowversion) parameters: 1. highversion?address of a dword variable that will contain the top 32 bits of the dll version. 2. lowversion?address of a dword variable that wi ll contain the bottom 32 bits of the dll version. return value: si_status = si_success or si_system_error_code
an169 rev. 2.3 17 4. device interface functions the usbxpress firmware libra ry implements a set of de vice interface functions th at provide an application programming interface (api) on the c8051f32x, c8 051f34x, c8051f38x, c8051t32x, and c8051t62x microcontrollers. these functions provide a simplified i/o interface to the mcu's usb co ntroller, thus eliminating the need to understand and manage low-level usb hardware or protocol details. the api is provided in the form of a library file precompiled under the keil c51 tool chain. device firmware must be developed using the keil software c51 tool chain. the device interface functions available are: usb_clock_start() - initializes the usb clock usb_init() - enables the usb interface block_write() - writes a buffer of data to the host via the usb block_read() - reads a buffer of data from the host via the usb get_interrupt_source() - indicates the reason for an api interrupt usb_int_enable() - enables the api interrupts usb_int_disable() - disables api interrupts usb_disable() - disables the usb interface usb_suspend() - suspends the usb interrupts usb_get_library_version() - returns the usbxpress fi rmware libra ry version the api is used in an interrupt-driven mode. the user mu st provide an interrupt handler located at vector address 0x0083 (interrupt 16) for the 'f320/1/6/ 7 devices, or at vector address 0x00 8b (interrupt 17) for the 'f34x/'f38x/ 't32x/'t62x devices. this ha ndler will be called upon at any usb api in terrupt. once inside this isr, a call to get_interr upt_source is used to determine the source of the interrupt (this call also clears the pending interrupt flags). the usbxpress firmware library oper ates the mcu's u sb controller at usb full sp eed, and uses the bulk transfer type with a data payload of 64 bytes per packet. code developed for a specific mcu device family ('f320/ 1, 'f326/7, 'f34x, 'f38x, 't32 x, or 't62x) must us e usbxpress device firmware libraries specific to that family. see "appendix c?firmware library notes? for more technical details, and differences between the mcu device firmware libraries. note : the usb0 hardware interrupt located at vector address 0x0043 (interrupt 8) is claimed by usbxpress, and is used to handle low-level usb prot ocol details. the usb api interrupt (interrupt 16 for 'f320/1/6/7 devices and interrupt 17 for 'f34x devices) is a virtual interrupt generated by the usbxpress firm ware library whenever user code needs to be notified of a usbxpress event. the events are defined in the description of the get_interr upt_source function. example isr for firmware api (interrupt 16 for 'f32x dev ices, interrupt 17 for 'f34x/'f38x/'t32x/'t62x devices): void usb_api_test_isr(void) interrupt 16 { byte intval = get_interrupt_source(); if (intval & tx_complete) { block_write(in_packet, 8); } if (intval & rx_complete) { block_read(out_packet, 8); }
an169 18 rev. 2.3 if (intval & dev_configured) { // initialize all analog peripherals here. this interrupt // tells the device that it can now use as much current as // specified by the maxpower descriptor. init(); // note: example command, not part of the api } if (intval & dev_suspend) { // turn off all analog peripherals turn_off_all(); // note: example command, not part of the api usb_suspend(); // this function returns once resume // signalling is present. // turn all analog peripherals back on init(); // note: example command, not part of the api } } 4.1. usb_clock_start description: enables the internal oscillator, initializes the clock multip lier, and sets the usb clock to 48 mhz for usb full speed operation. if the clock multiplie r is already initialized, the initialization proce- dure is skipped. this functi on should be called before calling usb_init or accessing any vari- ables located in the u pper 1024 bytes of xram (usb clock domain). clksel [1:0] is not affected by this function. see "appendix a?sfrs that should not be modified after calling usb_- clock_start and usb_init? for mo re details. see "appendix c?firmware library notes? for instructions on how to use the ex ternal oscillator as the usb clock. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t320/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_clock_start (void) parameters: none return value: none
an169 rev. 2.3 19 4.2. usb_init description: enables the usb interface, the usb clock recovery feature, and the use of device interface functions. on return, the usb interface is configured, and c8051f32x interrupts are globally enabled. user software should not globally disa ble interrupts (set ea = 0), but should enable or disable user configured interrupts individually using the interrupt's source interrupt enable flag present in the ie, eie1, or eie2 sfrs. before calling usb_init , a call to usb_clock_start should be made to configure the usb clock. see "appendi x a?sfrs that should not be modified after calling usb_clock_start and u sb_init? for more details. this function allows the user to specify the vendor and product ids as well as manufacturer, product description, and serial number strings that are sent to the host as part of the device's usb descriptor during the usb enumeration (device connection). supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_init (uint vendorid, uint productid, byte *manufacturerstr, byte *productstr, byte *serialnumberstr, byte maxpower, byte pwattributes, uint bcddevice) parameters: 1. vendorid ?16-bit vendor id to be returned to the host's operating system during usb enumeration. set to 0x10c4 to use the default silicon laboratories vendor id. 2. productid ?16-bit product id to be returned to the host's operating system during usb enumeration. set to 0xea6 1 to associate with the default usbxpress driver. 3. manufacturerstr ?pointer to a character string. see appendix b for formatting. null pointer should not be used because the library does not contain a default value for this string. 4. productstr ?pointer to a character string. see appendix b for formatting. null pointer should not be used because the library does no t contain a default value for this string. 5. serialnumberstr ?pointer to a character string. see appendix b for formatting. null pointer should not be used because the library does not contain a default value for this string. 6. maxpower ?specifies how much bus current a device requires. set to one half the number of milliamperes required. the maximum allowed current is 500 milliamperes, and hence any value above 0xfa will be automat ically set to 0xfa. example: set to 0x32 to request 100 ma. 7. pwattributes ?set bit 6 to 1 if the device is self-powered and to 0 if it is bus-powered. set bit 5 to 1 if the device supports the remote wakeup feature. bits 0 through 4 must be 0 and bit 7 must be 1. example: set to 0x80 to specif y a bus-powered device that does not support remote wakeup. 8. bcddevice ?the device's release number in bcd (bi nary-coded decimal) format. in bcd, the upper byte represents the integer, the next four bits are tenths, and the final four bits are hundredths. example: 2.13 is denoted by 0x0213. return value: none
an169 20 rev. 2.3 4.3. block_write description: writes a buffer of data to the host via usb. maximum block size is 4096 bytes. returns the num- ber of bytes actually written. this matches the parameter numbytes unless an error condition occurs. a zero is returned if block_write is called with numbytes grea ter than 4096. if numbytes is greater than 64 bytes, the bulk transaction is split into multiple pack ets, each with a 64-byte data payload (except last packet). block_write returns after copying the last packet to the device usb transmit buffer. the completion of the transa ction is then indicated by the tx_complete usb api interrupt. si_read can read from 0 to 64 kb of data. if block_write is called multiple times before si_read is called then there is potential to read all of the data in the host's buffer depending on the amount of data requested in the read. for example, if block_write is called 4 times, and sends a byte of data in each block the host side can call si_read requesting 4 bytes and get the data from all 4 of the block_writes at once. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: uint block_write (byte *buffer, uint numbytes) parameters: 1. buffer ?pointer to a memory location where data to be written is stored. 2. numbytes ?number of bytes to write (1?4096). return value: returns an unsigned 16-bit value indicating the number of bytes actually written. 4.4. block_read description: reads a buffer of data sent from the host via u sb. maximum block size is 64 bytes. the block of data is copied from the usb interface to the memory location pointed to by buffer. the device usb receive buffer will be emptied on return rega rdless of whether or not the entire buffer was read by block_read . the maximum number of bytes to read from the device usb receive buffer is specified in numbytes. the number of bytes act ually read (copied to buffer) is returned by the function. a zero is returned if there are no bytes to read. typically, block_read should be called after receiving a data packet, indicated by an rx_complete usb api interrupt. multiple calls to block_read might be needed to read all data sent via one si_write call if the buffer sent to si_write is more than 64 bytes. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: byte block_read (byte *buffer, byte numbytes) parameters: 1. buffer ?pointer to a memory location where data will be copied. 2. numbytes ?number of bytes to read (1?64). return value: returns an unsigned 8-bit value indicating the number of bytes actually read.
an169 rev. 2.3 21 4.5. get_interrupt_source description: returns an 8-bit value indicating the reason(s) for the api interrupt, and clears the usb api interrupt pending flag(s). this function should be called at the beginning of the user's interrupt service routine to determine which event(s) has/have occurred. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: byte get_interrupt_source (void) parameters: none return value: returns an unsigned 8-bit code indicating the reason(s) for the api interrupt. the code can indi- cate more than one type of interrupt at the sa me time. the return values are coded as follows: 0x00 no usb api interrupts have occurred 0x01 usb_reset usb reset interrupt has occurred 0x02 tx_complete transmit comp lete interrup t has occurred 0x04 rx_complete receive comp lete interrupt has occurred 0x08 fifo_purge command received (and serviced) from the host to purge the usb buffers 0x10 device_open device instance opened on host side 0x20 device_close device instance closed on host side 0x40 dev_configured device has entered configured state 0x80 dev_suspend usb suspend signaling present on bus 4.6. usb_int_enable description: a call to this function enables the usb api to generate interrupts. if enabled, a usb api interrupt is generated on the following api events: 1. a usb reset has occurred. 2. a transmit scheduled by a call to block_write has completed. 3. the rx buffer is ready to be serviced by a call to block_read . 4. a command from the host has caused the usb buffers to be flushed. 5. a device instance has been ope ned or closed by the host. the cause of the interrupt can be determined by a call to get_interr upt_source . if usb api inter- rupts are enabled, the user must provide an interr upt service routine with the entry point located at the interrupt 16 vector (add ress = 0x0083). when this function is called, control will transfer to the interrupt 16 handler within one ms, if any interrupts are currently pending. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_int_enable (void) parameters: none return value: none
an169 22 rev. 2.3 4.7. usb_int_disable description: this function disables the usb api interrupt generation. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_int_disable (void) parameters: none return value: none 4.8. usb_disable description: this function disables the usb interface and the use of device interface functions. on return, the usb interface is no longer available and api interrupts are turned of f. the clock multiplier is turned off to reduce power consumption unless the system clock is set to the '4x clock multiplier/2' op tion (clksel[1:0] = 10b). supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_disable (void) parameters: none return value: none 4.9. usb_suspend description: this function allows devices to meet the usb suspend current specification. to be usb compli- ant, a usb device must support the suspend feat ure by reducing its total power consumption to be under 500 a. this function should only be called when the dev_suspend usb api inter- rupt is received. all unnecessary user peripherals should be turned off be fore making this func- tion call, and can be turned back on after the ca ll returns. this routi ne powers down the usb transceiver and the clock multip lier and then suspends the inte rnal oscillator until usb resume signaling occurs. once usb tr affic is detected, internal oscillator is restarted, usb_clock_start is called, and then the function call returns to user code. note: usb_suspend will set the system clock to internal oscillator by default. if system clock is set to clock multiplier when usb_suspend is called, that setting will be restored before this function returns. if it is necessary to use any other setting for system clock, us er code should modify clksel on return from usb_suspend . supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t320/1/2/3/6/7, c8051t620/1/2/3 prototype: void usb_suspend (void) parameters: none return value: none
an169 rev. 2.3 23 4.10. usb_get_library_version description: this function returns the usbxpre ss firmware library version numb er in bcd. this function is available in usbxpress firmware libraries from release 2.4 and above. example: rev. 2.41 is returned as 0x0241. supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t3 20/1/2/3/6/7, c8051t620/1/2/3 prototype: uint usb_get_library_version (void) parameters: none return value: returns the usbxp ress firmware library version number as an unsigned 16-bit value in bcd for- mat.
an169 24 rev. 2.3 a ppendix a?sfr s that s hould n ot be m odified a fter c alling usb_c lock _s tart and usb_i nit supported devices: c8051f320/1/6/7, c8051f340/ 1/2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t320/1/2/3/6/7, c8051t620/1/2/3 the following is a list of sfrs configured by the api. thes e should not be altered at any time after the first call to usb_clock_start or usb_init . most of these sfrs are dedicated to the usb peripheral on the chip and should be of no concern to the programmer under most circumstances. off-limits usb sfrs?usb0xc n, usb0adr, and usb0dat off-limits other sfrs?clkmul, oscicn (only bits 5?7 are off-limits), clksel (only bits 4?6 are off-limits). these three sfrs are used to enable th e internal oscillator, engage the 4x cl ock multiplier to 48 mhz, and to use that as the clock for the usb core. for the api to function properly, these should not be modified. api?user shared sfrs: the clksel sfr is used for choosing both the system clock source and usb clock source. care should be used to or in the system clock de sired into bits 1?0, so as not to disturb bits 6?4, which are the usb clock selection bits. the oscicn sfr is used to control the internal oscillator. the if cn[1:0] bits can be modifi ed as required by the user to modify the system clock frequency. note that the ifcn bits do not affect the 12 mhz clock multiplier input or the usb clock. care should be taken to preserve bits 5?7 while modifying the ifcn bits.
an169 rev. 2.3 25 a ppendix b?f ormat of u ser -d efined p roduct d escription and s erial n umber s trings supported devices: c8051f320/1/6/7, c8051f340/ 1/2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t320/1/2/3/6/7, c8051t620/1/2/3 it is possible for the api to use strings defined and allocated in user firmware instead of the api default strings. the syntax for defining and using custom strings is: unsigned char customstring[]={number of string elements,0x03,'a',0,'b',0,'c',0...'z',0}; the number of string elements = number of letters x 2 + 2, since every letter needs to be separated from the next by zeros, and usb requires that the first element be th e length, and the second element is 0x03, meaning string descriptor type. this sounds harder than it is, for example: //abc inc unsigned char customstring1[]={16,0x03,'a',0,'b',0,'c',0,' ',0,'i',0,'n',0,'c',0}; //widget unsigned char customstring2[]={14,0x03,'w',0,'i',0,'d',0,'g',0,'e',0,'t',0}; //12345 unsigned char customstring3[]={12,0x03,'1',0,'2',0,'3',0,'4',0,'5',0}; then, if the vendor id and product id were 0xabcd and 0x1123, the call to usb_init would be usb_init (0xabcd, 0x1123, customstring1, customstring2, customstring3); note: it is useful to use the code keywor d preceding the customstring definition s, so that the strings are located in code space.
an169 26 rev. 2.3 a ppendix c?f irmware l ibrary n otes supported devices: c8051f320/1/6/7, c8051f340/ 1/2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051t320/1/2/3/6/7, c8051t620/1/2/3 tool chain the usbxpress firmware library has been developed with th e keil c51 tool chain, and is distributed as a pre- compiled library. hence the user project should be built using the keil c51 tool chain, with the usb_api.lib included as an external library. a header file usb_api.h with macro definitions and function prototypes is also provided. memory-model concerns the firmware api library was created using the small memory model. using this library in a project with a default memory model of large or compact can cause warnings to occur, depending on warning level settings. to avoid this, set the default memory model to small, and override this setting wherever necessary by defining each function with the large compiler keyword. the ?using? keyword the ?using? keyword should not be used with the usb api is r. this compile-time optimi zation is not supported by the usbxpress library code that is used to create the virtua l usb api interrupt (interrupt # 16). internal functions and variables all internal function names and glob al variable names in the usbxpress fi rmware library begin with the prefix ?usbxcore?. to avoid conflict with these public symbols that will, if duplicated, re sult in ?multiple public definitions? errors, global variables and function names in user firmwar e should not begin with this prefix. using external oscillator or clock by default, usbxpress uses the inter nal 12 mhz oscillator along with the 4x clock multiplier as the usb clock. to override this, the user firmware can provide its own usb_clock_start function. the keil linke r will then override the library function with the user-supplied function. if a high pr ecision external crystal or clock is used, you may want to turn off the usb clock recovery feature. to do this, user firmware code should include a dummy function definition as shown below. this will ov erride the corresponding inter nal function in the library. void usbxcore_clkrec(void) large { } saving xdata space the usb_init function parameters are passed in direct memory locations in user xdata space determined by the linker. if user firmware needs this contiguous space, these 17 bytes can be relocated to unused xdata space within the usbxpress reserved area. to do this, the fo llowing should be added to the command line while invoking the linker (the value for ?address? is shown in table 1): xdata(?xd?_usb_init?usb_api(

)) example: bl51.exe file1.obj,file2.obj,filen.obj,usb_api.lib to prj1 rs(256) pl(68) pw(78)xdata(?xd?_usb_init?usb_api(0x03ef))
an169 rev. 2.3 27 firmware library code size and other details the flash memory occupied by the u sbxpress firmware library dep ends on the number of library functions used by the user application. this is becau se the linker includes only the called functions in the build. if all usbxpress functions are used, the library would occupy ~3 kb of code memory. the low-level settings configured by the usbxpress firmware library are shown in table 1. table 1. firmware library technical details c8051f320/1 c8051f326/7 c8051f340/1/2/3/4/5/6/7/8/ 9/a/b/c/d internal oscillator 1 enabled (oscicn.7 = 1) 4x clock multiplier 1 enabled (source: in ternal oscillator) usb clock recovery 1 enabled (clkrec = 0x89) usb clock source 1 clock multiplier (48 mhz) usb speed full speed (12 mbps) usb transfer type bulk transfer max data payload size (control endpoint, ep0) 64 bytes per data packet number of bulk data endpoints used 2 (ep2 in split mode) 2 (ep1 in split mode) 2 (ep2 in split mode) max data payload size (bulk data endpoints) 64 bytes per data packet double buffering enabled for both in and out endpoints (fifo can hold two packets each at any time). enabled for out endpoint (fifo can hold two packets at any time). disabled for in endpoint. enabled for both in and out endpoints (fifo can hold two packets each at any time). xdata space reserved by the library 2 448 bytes xdata (0x0640 to 0x07ff) [includes usb fifo space] 128 bytes (0x0380 to 0x03ff) xdata + 256 bytes (0x00 to 0xff) usb fifo 448 bytes xdata (0x0640 to 0x07ff) [includes usb fifo space] starting address to relocate usb_init function parameters (see " saving xdata space" on page 26) 0x07af 0x03ef 0x07af usbxpress firmware library name usbx_f320_1.lib usbx_f3 26_7.lib usbx_f34x.lib c8051f380/1/2/3/4/5/6/7 c8051t620/1 and c8051t320/1/2/3 c8051t622/3 and c8051t326/7 notes: 1. the clock settings listed in this table are valid only if the default usbxpress clock fu nctions (usb_clock_start and usbxcore_clkrec) are not overridden by user firmware. 2. this reserved space includes the relocated usb_init parame ters using linker commands. see " saving xdata space" on page 26 for more details. this only applies to the keil libraries.
an169 28 rev. 2.3 internal oscillator 1 enabled (oscicn.7 = 1) 4x clock multiplier 1 enabled (source: in ternal oscillator) usb clock recovery 1 enabled (clkrec = 0x8f) usb clock source 1 clock multiplier (48 mhz) usb speed full speed (12 mbps) usb transfer type bulk transfer max data payload size (control endpoint, ep0) 64 bytes per data packet number of bulk data endpoints used 2 (ep2 in split mode) 2 (ep2 in split mode) 2 (ep1 and ep2) max data payload size (bulk data endpoints) 64 bytes per data packet double buffering enabled for both in and out endpoints (fifo can hold two packets each at any time). enabled for both in and out endpoints (fifo can hold two packets each at any time). enabled for out endpoint (fifo can hold two packets at any time). disabled for in endpoint. xdata space reserved by the library 2 448 bytes xdata (0x0640 to 0x07ff) [includes usb fifo space] 448 bytes xdata (0x0640 to 0x07ff) [includes usb fifo space] 116 bytes (0x038c to 0x03ff) xdata + 256 bytes (0x0400 to 0x04ff) usb fifo starting address to relocate usb_init function parameters (see " saving xdata space" on page 26) 0x07af 0x07af 0x3ef usbxpress firmware library name usbx_f38x.lib usbx_t620_1_320_ 3.lib usbx_t622_3 _t326_7.lib table 1. firmware library technical details (continued) notes: 1. the clock settings listed in this table are valid only if the default usbxpress clock fu nctions (usb_clock_start and usbxcore_clkrec) are not overridden by user firmware. 2. this reserved space includes the relocated usb_init parame ters using linker commands. see " saving xdata space" on page 26 for more details. this only applies to the keil libraries.
an169 rev. 2.3 29 type definitions from firmware library header file usb_api.h // uint type definition #ifndef _uint_def_ #define _uint_def_ typedef unsigned int uint; #endif /* _uint_def_ */ // byte type definition #ifndef _byte_def_ #define _byte_def_ typedef unsigned char byte; #endif /* _byte_def_ */
an169 30 rev. 2.3 a ppendix d?d efinitions from c++ header file siusbx p . h supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 // return codes #define si_success 0x00 #define si_device_not_found 0xff #define si_invalid_handle 0x01 #define si_read_error 0x02 #define si_write_error 0x04 #define si_reset_error 0x05 #define si_invalid_parameter 0x06 #define si_invalid_request_length 0x07 #define si_device_io_failed 0x08 #define si_invalid_baudrate 0x09 #define si_function_not_supported 0x0a #define si_global_data_error 0x0b #define si_system_error_code 0x0c #define si_read_timed_out 0x0d #define si_write_timed_out 0x0e #define si_io_pending 0x0f // getproductstring() function flags #define si_return_serial_number 0x00 #define si_return_description 0x01 #define si_return_link_name 0x02 #define si_return_vid 0x03 #define si_return_pid 0x04 // rx queue status flags #define si_rx_no_overrun 0x00 #define si_rx_empty 0x00 #define si_rx_overrun 0x01 #define si_rx_ready 0x02 // buffer size limits #define si_max_device_strlen 256 #define si_max_read_size 4096*16 #define si_max_write_size 4096 // type definitions typedef int si_status; typedef char si_device_string[si_max_device_strlen]; // input and output pin characteristics
an169 rev. 2.3 31 #define si_held_inactive 0x00 #define si_held_active 0x01 #define si_firmware_controlled 0x02 #define si_receive_flow_control 0x02 #define si_transmit_active_signal 0x03 #define si_status_input 0x00 #define si_handshake_line 0x01 // mask and latch value bit definitions #define si_gpio_0 0x01 #define si_gpio_1 0x02 #define si_gpio_2 0x04 #define si_gpio_3 0x08 // getdeviceversion() return codes #define si_CP2101_version 0x01 #define si_cp2102_version 0x02 #define si_cp2103_version 0x03 #define si_cp2104_version 0x04 #define si_cp2105_version 0x05 // common variable and type definitions used typedef unsigned long dword; typedef int bool; typedef unsigned char byte; typedef unsigned short word; typedef byte near *pbyte; typedef dword near *pdword; typedef dword far *lpdword; typedef void far *lpvoid;
an169 32 rev. 2.3 a ppendix e?e rror c ode e xplanations and d ebugging supported devices: c8051f320/1/6/7, c8051f340/1/ 2/3/4/5/6/7/8/9/a/b/c/d, c8051f380/1/2/3/4/5/6/7, c8051 t320/1/2/3/6/7, c8051t620/1/2/3, CP2101/2/3/4/5/8/9 si_success the function succeeded. si_device_not_found the device cannot be found on the system. make sure the device is plugged in and powered. if the device is plugged in, make sure that all previous applic ation handles to the device have been closed ( si_close ). if a previous instance of the application was not able to clos e its handle to the device before exiting, disconnect and reconnect the device. to avoid having to temporarily remove the device in this case, you may have your application store the current handle value (returned by si_open ) in the windows registry so that if the application crashes, the handle is still accessible and can be closed ( si_close ). si_invalid_handle the value of the handle passed to the function is not valid. a valid handle is obtained by declaring a handle variable in your program and passing the address of that handle to the si_open function. a handle may become invalid if the device is remove d from the system, so first verify that the device is connected. si_write_error the write operation failed. the device may have been removed. si_invalid_parameter an invalid parameter was passed to the dll function called. see the function definition for valid parameter types and/or ranges. si_invalid_request_length see si_read and si_write function descriptions for valid request lengths. si_device_io_failed device io operation failed. the device may have been removed. si_invalid_baudrate see the cp210x device-specific da ta sheet for supported baud rates. si_function_not_supported the function called is not supported by the device. for example, attempting to use the si_readlatch and si_writelatch functions on a device other than the cp2103 will cause the func tions to return this value. si_global_data_error an error has occurred such that the thread global data cannot be retrieved. unload and reload the dll if this return code is received. si_system_error_code call getlasterror (win32 base) to retrieve windows sy stem error code. the error codes are defined on msdn.
an169 rev. 2.3 33 si_read_timed_out or si_write_timed_out the read or write request timed out based on the current timeout values. si_io_pending i/o is pending, wait on the over lapped object supplied to the si_read or si_write function using waitforsingleobject() or getoverlappedresult() as documented on msdn by microsoft, and/or si_cancelio() .
an169 34 rev. 2.3 a ppendix f?u pdating h ost c ode to w ork u nder usbxpress 3.x.x note : the usbxpress 3.x.x package works diff erent functionally from previous versions (2 .42 and earlier). do not mix and match any of thes e old dlls or drivers with any pa rt of the 3.x.x package. this will result in data error and possibly a system crash. the si_close() function has changed from si_close(& handle handle) to si_close (handle handle). versions before 3.x.x would set the handle value to invalid_ handle_value when a close was called. now it is the responsibility of the developer to set the handle value to be invalid. for vi sual basic users, this change will also require a declare statement modification. the correct way to call this function in vb is: public declare function si _close lib "siusbxp.dll" _ (byval cyhandle as long) as integer the read and write functions have ch anged to include a parameter for a pointer to an in itialized overlapped object. for c++ users the prototype has been set so that th is parameter is false by default allowing older code to be ported directly. for vb users the declare statements will have to be updated as follows: public declare function si_read lib "siusbxp.dll" _ (byval cyhandle as long, byref lpbuffer as byte, _ byval dwbytestoread as long, byre f lpdwbytesreturned as long, _ byval lpoverlapped as long) as integer public declare function si _write lib "siusbxp.dll" _ (byval cyhandle as long, byref lpbuffer as byte, _ byval dwbytestowrite as long, byref lpdwbyteswritten as long, _ byval lpoverlapped as long) as integer
an169 rev. 2.3 35 d ocument c hange l ist revision 1.6 to revision 1.7 ? updated all host api info rmation to reflect 3.x.x changes. see "appendix f?updating host code to work under usbxpress 3.x.x? for important compatibility information. ? device api documentation: ?? updated description in "3. device interface functions" to reflect support for 'f326/7 and 'f34x devices. ?? added description of function "3.10. usb_get_library_version". ?? updated table 1 to show details of the 'f326/7 and 'f34x device firmware libraries. revision 1.7 to revision 1.8 ? modified return values for si_write. ? modified descriptions of blocking in si_write/ si_read. ? further explained the block_write in relation to si_read. revision 1.8 to revision 1.9 ? modified return values for si_read. ? removed references to unused return code si_rx_queue_not_ready ? modified to explain si_getdllversion and si_getdriverversion revision 1.9 to revision 2.0 ? updated functions return values in "3. host api functions" on page 3. ? corrected prototype declaration for "3.5. si_read" on page 6 and "3.6. si_write" on page 7. revision 2.0 to revision 2.1 ? added cp2104 and cp2105 to relevant devices on page 1. ? updated host api functions to reflect support for cp2104 and cp2105 devices. revision 2.1 to revision 2.2 ? added support for c8051f38x, c8051t32x, and c8051t62x devices. revision 2.2 to revision 2.3 ? added support for cp2108 and cp2109. ? updated cancelio() to si_cancelio() and added the si_cancelio() api information. ? added "2. usbxpress versions" on page 2. ? updated xdata space reserved by the library for c8051f326/7, c8051t622/3, and c8051t326/7 in table 1 on page 27. ? updated note 2 in table 1 on page 27.
an169 36 rev. 2.3 c ontact i nformation silicon laboratories inc. 400 west cesar chavez austin, tx 78701 tel: 1+(512) 416-8500 fax: 1+(512) 416-9669 toll free: 1+(877) 444-3032 please visit the silicon labs technical support web page: https://www.silabs.com/support/pages/contacttechnicalsupport.aspx and register to submit a technical support request. patent notice silicon labs invests in research and development to help our cust omers differentiate in the market with innovative low-power, s mall size, analog- intensive mixed-signal soluti ons. silicon labs' extensive pat ent portfolio is a testament to our unique approach and world-clas s engineering team. silicon laboratories and silicon labs are trademarks of silicon laboratories inc. other products or brandnames mentioned herein are trademarks or registered trademarks of their respective holders. the information in this document is believed to be accurate in all respects at the time of publ ication but is subject to change without notice. silicon laboratories assumes no responsibility for errors and om issions, and disclaims responsibi lity for any consequences resu lting from the use of information included herein. ad ditionally, silicon laboratorie s assumes no responsibility for the functioning of und escribed features or parameters. silicon laboratories reserves the right to make changes without further notice . silicon laboratories makes no wa rranty, rep- resentation or guarantee regarding the suitability of its products for any particular purpose, nor does silicon laboratories as sume any liability arising out of the application or use of any product or circuit, and s pecifically disclaims any and all liability, including wi thout limitation conse- quential or incidental damages. silicon laborat ories products are not designed, intended, or authorized for use in applications intended to support or sustain life, or for any other application in which the failure of t he silicon laboratories product could create a s ituation where per- sonal injury or death may occur. should buyer purchase or us e silicon laboratories products for any such unintended or unauthor ized ap- plication, buyer shall indemnify and hold silicon laboratories harmles s against all claims and damages.

▲Up To Search▲

Price & Availability of CP2101

	To Download CP2101 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .